Working With Progress and Cover Functions2

The Movie Toolbox allows your application to assign two types of custom functions: progress functions and cover functions. These functions allow you to perform special processing under certain circumstances.

Some Movie Toolbox functions can take a long time to execute. For example, if you call the FlattenMovie function and specify a large movie, the Movie Toolbox must read and write all the sample data for the movie. During such operations you may wish to display some kind of progress indicator to the user.

A progress function is an application-defined function that you can use to track the progress of time-consuming activities, and thereby keep the user informed about that progress.

The Movie Toolbox allows your application to perform custom processing whenever one of your movie's tracks covers a screen region or reveals a region that was previously covered. You perform this processing in cover functions.

There are two types of cover functions: those that are called when your movie covers a screen region, and those that are called when your movie uncovers a screen region that was previously covered. Cover functions that are called when your movie covers a screen region are responsible for erasing the region--you may choose to save the hidden region in an offscreen buffer. Cover functions that are called when your movie reveals a hidden screen region must redisplay the hidden region.

Note
The Movie Toolbox does not call your cover function in response to changes to the movie's transformation matrix (for example, changing the matrix by calling the SetMovieBox function, which is described on SetMovieBox , does not cause your cover function to be invoked).

The SetMovieProgressProc function helps your application work with progress functions and the SetMovieCoverProcs function helps your application work with cover functions.

SetMovieProgressProc

The SetMovieProgressProc function allows you to attach a progress function to each movie. The function will be called whenever a long operation is underway. The Movie Toolbox indicates the progress of the operation to your progress function.

The Movie Toolbox ensures that your progress function is called regularly, but not too often. In addition, the toolbox calls your function only during long operations.



 
pascal void SetMovieProgressProc (Movie theMovie,

                                          MovieProgressUPP p, 

                                          long refCon);

theMovie: Specifies the movie for this operation. Your application obtains this movie identifier from such functions as NewMovie , NewMovieFromFile , and NewMovieFromHandle (described on NewMovie , NewMovieFromFile , and NewMovieFromHandle , respectively).
p: Points to your progress function. To remove a movie's progress function, set this parameter to nil . Set this parameter to -1 for the Movie Toolbox to provide a default progress function. See "Progress Functions," for the interface your progress function must support.
refCon: Specifies a reference constant. The Movie Toolbox passes this value to your progress function.

DESCRIPTION

The following Movie Toolbox functions use progress functions: ConvertFileToMovieFile (described on ConvertFileToMovieFile ), CutMovieSelection (described on CutMovieSelection ), CopyMovieSelection (described on CopyMovieSelection ), AddMovieSelection (described on AddMovieSelection ), and InsertMovieSegment (described on InsertMovieSegment ).

ERROR CODES

invalidMovie

-2010

This movie is corrupted or invalid

SetMovieCoverProcs

The SetMovieCoverProcs function allows you to set both types of cover functions.



 
pascal void SetMovieCoverProcs (Movie theMovie, 

                                         MovieRgnCoverUPP uncoverProc,

                                         MovieRgnCoverUPP coverProc,

                                         long refcon);

theMovie: Specifies the movie for this operation. Your application obtains this movie identifier from such functions as NewMovie , NewMovieFromFile , and NewMovieFromHandle (described on NewMovie , NewMovieFromFile , and NewMovieFromHandle , respectively).
uncoverProc: Points to a cover function. This function is called whenever one of your movie's tracks is removed from the screen or resized, revealing a previously hidden screen region. If you want to remove the cover function, set this parameter to nil . When the uncoverProc parameter is nil , SetMovieCoverProcs uses the default cover or uncover function. The default cover function does nothing. The default uncover function erases the uncovered area. See "Cover Functions," for the interface your cover function must support.
coverProc: Points to a cover function. The Movie Toolbox calls this function whenever one of your movies covers a portion of the screen. If you want to remove the cover function, set this parameter to nil . See "Cover Functions," for the interface your cover function must support.
refcon: Specifies a reference constant. The Movie Toolbox passes this value to your cover functions.

ERROR CODES

invalidMovie

-2010

This movie is corrupted or invalid